
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_Hans">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>表单 API &#8212; Django 3.2.11.dev 文档</title>
    <link rel="stylesheet" href="../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <link rel="index" title="索引" href="../../genindex.html" />
    <link rel="search" title="搜索" href="../../search.html" />
    <link rel="next" title="表单字段" href="fields.html" />
    <link rel="prev" title="表单" href="index.html" />



 
<script src="../../templatebuiltins.js"></script>
<script>
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);</script>

  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Django 3.2.11.dev 文档</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../index.html">Home</a>  |
        <a title="Table of contents" href="../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../genindex.html">Index</a>  |
        <a title="Module index" href="../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="index.html" title="表单">previous</a>
     |
    <a href="../index.html" title="API 参考" accesskey="U">up</a>
   |
    <a href="fields.html" title="表单字段">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="ref-forms-api">
            
  <div class="section" id="s-module-django.forms">
<span id="s-the-forms-api"></span><span id="module-django.forms"></span><span id="the-forms-api"></span><h1>表单 API<a class="headerlink" href="#module-django.forms" title="永久链接至标题">¶</a></h1>
<div class="admonition-about-this-document admonition">
<p class="first admonition-title">关于此文档</p>
<p class="last">本文档介绍了 Django 的表单 API 的具体细节。你应该先阅读 <a class="reference internal" href="../../topics/forms/index.html"><span class="doc">使用表单的介绍</span></a>。</p>
</div>
<div class="section" id="s-bound-and-unbound-forms">
<span id="s-ref-forms-api-bound-unbound"></span><span id="bound-and-unbound-forms"></span><span id="ref-forms-api-bound-unbound"></span><h2>绑定和非绑定表单<a class="headerlink" href="#bound-and-unbound-forms" title="永久链接至标题">¶</a></h2>
<p>一个 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例要么是 <strong>绑定</strong> 到一组数据，要么是 <strong>未绑定</strong>。</p>
<ul class="simple">
<li>如果是 <strong>绑定</strong> 了一组数据，它就能够验证这些数据，并将表单渲染成 HTML，并在 HTML 中显示数据。</li>
<li>如果是 <strong>未绑定</strong>，它就不能进行验证（因为没有数据可验证！），但它仍然可以将空白表单渲染为 HTML。</li>
</ul>
<dl class="class">
<dt id="django.forms.Form">
<em class="property">class </em><code class="descname">Form</code><a class="headerlink" href="#django.forms.Form" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>要创建一个未绑定的 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例，实例化类：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
</pre></div>
</div>
<p>要将数据绑定到表单中，将数据以字典的形式传递给你的 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 类构造函数的第一个参数：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hello&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;foo@example.com&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
<p>在这个字典中，键是字段名，对应于 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 类中的属性。值是你要验证的数据。这些数据通常是字符串，但不要求它们是字符串；你传递的数据类型取决于 <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a>，我们稍后会看到。</p>
<dl class="attribute">
<dt id="django.forms.Form.is_bound">
<code class="descclassname">Form.</code><code class="descname">is_bound</code><a class="headerlink" href="#django.forms.Form.is_bound" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>如果你需要在运行时区分绑定和未绑定的表单实例，请检查表单的 <a class="reference internal" href="#django.forms.Form.is_bound" title="django.forms.Form.is_bound"><code class="xref py py-attr docutils literal notranslate"><span class="pre">is_bound</span></code></a> 属性的值：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_bound</span>
<span class="go">False</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">({</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hello&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_bound</span>
<span class="go">True</span>
</pre></div>
</div>
<p>需要注意的是，传递一个空的字典会创建一个空数据的 <em>绑定</em> 表单：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">({})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_bound</span>
<span class="go">True</span>
</pre></div>
</div>
<p>如果你有一个绑定的 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例，并想以某种方式改变数据，或者你想将一个未绑定的 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例绑定到一些数据，请创建另一个 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例。没有办法改变一个 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例中的数据。一旦创建了一个 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例，你应该认为它的数据是不可改变的，不管它是否有数据。</p>
</div>
<div class="section" id="s-using-forms-to-validate-data">
<span id="using-forms-to-validate-data"></span><h2>使用表单来验证数据<a class="headerlink" href="#using-forms-to-validate-data" title="永久链接至标题">¶</a></h2>
<dl class="method">
<dt id="django.forms.Form.clean">
<code class="descclassname">Form.</code><code class="descname">clean</code>()<a class="headerlink" href="#django.forms.Form.clean" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>当你必须为相互依赖的字段添加自定义验证时，在你的 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 上实现一个 <code class="docutils literal notranslate"><span class="pre">clean()</span></code> 方法。参见 <a class="reference internal" href="validation.html#validating-fields-with-clean"><span class="std std-ref">清理和验证相互依赖的字段</span></a> 的用法示例。</p>
<dl class="method">
<dt id="django.forms.Form.is_valid">
<code class="descclassname">Form.</code><code class="descname">is_valid</code>()<a class="headerlink" href="#django.forms.Form.is_valid" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p><a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 对象的主要任务是验证数据。有了一个绑定的 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例，调用 <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_valid()</span></code></a> 方法来运行验证，并返回一个布尔值，指定数据是否有效：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hello&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;foo@example.com&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">True</span>
</pre></div>
</div>
<p>让我们用一些无效的数据试试。在这种情况下，<code class="docutils literal notranslate"><span class="pre">subject</span></code> 是空白的（这是一个错误，因为所有的字段都是默认的），<code class="docutils literal notranslate"><span class="pre">sender</span></code> 不是一个有效的电子邮件地址：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;invalid email address&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">False</span>
</pre></div>
</div>
<dl class="attribute">
<dt id="django.forms.Form.errors">
<code class="descclassname">Form.</code><code class="descname">errors</code><a class="headerlink" href="#django.forms.Form.errors" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>访问 <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errors</span></code></a> 属性来获取错误信息的字典：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span>
<span class="go">{&#39;sender&#39;: [&#39;Enter a valid email address.&#39;], &#39;subject&#39;: [&#39;This field is required.&#39;]}</span>
</pre></div>
</div>
<p>在这个字典中，键是字段名，值是代表错误信息的字符串列表。错误信息存储在列表中，因为一个字段可以有多个错误信息。</p>
<p>你可以访问 <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errors</span></code></a>，而不必先调用 <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_valid()</span></code></a>。无论是调用 <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_valid()</span></code></a> 还是访问 <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errors</span></code></a>，表单的数据都会首先被验证。</p>
<p>验证例程只会被调用一次，无论你访问 <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errors</span></code></a> 或调用 <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_valid()</span></code></a> 多少次。这意味着，如果验证有副作用，这些副作用将只被触发一次。</p>
<dl class="method">
<dt id="django.forms.Form.errors.as_data">
<code class="descclassname">Form.errors.</code><code class="descname">as_data</code>()<a class="headerlink" href="#django.forms.Form.errors.as_data" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>返回一个 <code class="docutils literal notranslate"><span class="pre">dict</span></code>，将字段映射到它们的原始 <code class="docutils literal notranslate"><span class="pre">ValidationError</span></code> 实例。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">as_data</span><span class="p">()</span>
<span class="go">{&#39;sender&#39;: [ValidationError([&#39;Enter a valid email address.&#39;])],</span>
<span class="go">&#39;subject&#39;: [ValidationError([&#39;This field is required.&#39;])]}</span>
</pre></div>
</div>
<p>当你需要通过错误 <code class="docutils literal notranslate"><span class="pre">code</span></code> 来识别错误时，请使用此方法。这样就可以在给定的错误出现时，重写错误信息或在视图中编写自定义逻辑。它还可以用来以自定义格式（如 XML）将错误序列化；例如， <code class="xref py py-meth docutils literal notranslate"><span class="pre">as_json()</span></code> 依赖于 <code class="docutils literal notranslate"><span class="pre">as_data()</span></code>。</p>
<p>需要使用 <code class="docutils literal notranslate"><span class="pre">as_data()</span></code> 方法是由于向后兼容性。以前，<code class="docutils literal notranslate"><span class="pre">ValidationError</span></code> 实例一旦被添加到 <code class="docutils literal notranslate"><span class="pre">Form.errors</span></code> 字典中，其 <strong>渲染的</strong> 错误信息就会丢失。理想情况下，<code class="docutils literal notranslate"><span class="pre">Form.errors</span></code> 会存储 <code class="docutils literal notranslate"><span class="pre">ValidationError</span></code> 实例，并且带有 <code class="docutils literal notranslate"><span class="pre">as_</span></code> 前缀的方法可以渲染它们，但为了不破坏那些期望在 <code class="docutils literal notranslate"><span class="pre">Form.errors</span></code> 中渲染错误信息的代码，必须反过来做。</p>
<dl class="method">
<dt id="django.forms.Form.errors.as_json">
<code class="descclassname">Form.errors.</code><code class="descname">as_json</code>(<em>escape_html=False</em>)<a class="headerlink" href="#django.forms.Form.errors.as_json" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>返回以 JSON 格式序列化的错误。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">as_json</span><span class="p">()</span>
<span class="go">{&quot;sender&quot;: [{&quot;message&quot;: &quot;Enter a valid email address.&quot;, &quot;code&quot;: &quot;invalid&quot;}],</span>
<span class="go">&quot;subject&quot;: [{&quot;message&quot;: &quot;This field is required.&quot;, &quot;code&quot;: &quot;required&quot;}]}</span>
</pre></div>
</div>
<p>默认情况下，<code class="docutils literal notranslate"><span class="pre">as_json()</span></code> 不会转义其输出。如果你使用它来处理类似 AJAX 请求的表单视图，客户端解释响应并将错误插入到页面中，你会希望确保在客户端转义结果，以避免跨站点脚本攻击的可能性。你可以在 JavaScript 中使用 <code class="docutils literal notranslate"><span class="pre">element.textContent</span> <span class="pre">=</span> <span class="pre">errorText</span></code> 或者使用 jQuery 的 <code class="docutils literal notranslate"><span class="pre">$(el).text(errorText)</span></code> （而不是它的 <code class="docutils literal notranslate"><span class="pre">.html()</span></code> 函数）来实现。</p>
<p>如果出于某些原因你不想使用客户端转义，你也可以设置 <code class="docutils literal notranslate"><span class="pre">escape_html=True</span></code>，错误信息将被转义，这样你就可以直接在 HTML 中使用它们。</p>
<dl class="method">
<dt id="django.forms.Form.errors.get_json_data">
<code class="descclassname">Form.errors.</code><code class="descname">get_json_data</code>(<em>escape_html=False</em>)<a class="headerlink" href="#django.forms.Form.errors.get_json_data" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">Form.</span> <span class="pre">errors.as_json()</span></code> 将返回序列化的 JSON，而这个则是返回序列化之前的错误数据。</p>
<p><code class="docutils literal notranslate"><span class="pre">escape_html</span></code> 参数的行为如 <a class="reference internal" href="#django.forms.Form.errors.as_json" title="django.forms.Form.errors.as_json"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Form.errors.as_json()</span></code></a> 中所述。</p>
<dl class="method">
<dt id="django.forms.Form.add_error">
<code class="descclassname">Form.</code><code class="descname">add_error</code>(<em>field</em>, <em>error</em>)<a class="headerlink" href="#django.forms.Form.add_error" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>该方法允许在 <code class="docutils literal notranslate"><span class="pre">Form.clean()</span></code> 方法中添加错误到特定字段，或者从表单外部添加错误，例如从视图中添加。</p>
<p><code class="docutils literal notranslate"><span class="pre">field</span></code> 参数是应该添加错误的字段名。如果它的值是 <code class="docutils literal notranslate"><span class="pre">None</span></code>，错误将被视为非字段错误，就像 <a class="reference internal" href="#django.forms.Form.non_field_errors" title="django.forms.Form.non_field_errors"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Form.non_field_errors()</span></code></a> 返回的那样。</p>
<p><code class="docutils literal notranslate"><span class="pre">error</span></code> 参数可以是一个字符串，或者最好是 <code class="docutils literal notranslate"><span class="pre">ValidationError</span></code> 的实例。关于定义表单错误的最佳做法，请参见 <a class="reference internal" href="validation.html#raising-validation-error"><span class="std std-ref">引发 ValidationError</span></a>。</p>
<p>注意，<code class="docutils literal notranslate"><span class="pre">Form.add_error()</span></code> 会自动从 <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> 中删除相关字段。</p>
<dl class="method">
<dt id="django.forms.Form.has_error">
<code class="descclassname">Form.</code><code class="descname">has_error</code>(<em>field</em>, <em>code=None</em>)<a class="headerlink" href="#django.forms.Form.has_error" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>本方法返回一个布尔值，表示一个字段是否有特定错误 <code class="docutils literal notranslate"><span class="pre">code</span></code> 的错误。如果 <code class="docutils literal notranslate"><span class="pre">code</span></code> 是 <code class="docutils literal notranslate"><span class="pre">None</span></code>，如果字段包含任何错误，它将返回 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
<p>要检查非字段错误，使用 <a class="reference internal" href="../exceptions.html#django.core.exceptions.NON_FIELD_ERRORS" title="django.core.exceptions.NON_FIELD_ERRORS"><code class="xref py py-data docutils literal notranslate"><span class="pre">NON_FIELD_ERRORS</span></code></a> 作为 <code class="docutils literal notranslate"><span class="pre">field</span></code> 参数。</p>
<dl class="method">
<dt id="django.forms.Form.non_field_errors">
<code class="descclassname">Form.</code><code class="descname">non_field_errors</code>()<a class="headerlink" href="#django.forms.Form.non_field_errors" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>这个方法从 <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.errors</span></code></a> 中返回没有与特定字段关联的错误列表。这包括在 <a class="reference internal" href="#django.forms.Form.clean" title="django.forms.Form.clean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Form.clean()</span></code></a> 中引发的 <code class="docutils literal notranslate"><span class="pre">ValidationError</span></code> 和使用 <a class="reference internal" href="#django.forms.Form.add_error" title="django.forms.Form.add_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Form.add_error(None,</span> <span class="pre">&quot;...&quot;)</span></code></a> 添加的错误。</p>
<div class="section" id="s-behavior-of-unbound-forms">
<span id="behavior-of-unbound-forms"></span><h3>非绑定表单的行为<a class="headerlink" href="#behavior-of-unbound-forms" title="永久链接至标题">¶</a></h3>
<p>在没有数据的情况下验证表单是没有意义的，但是，记录一下，以下是未绑定表单的情况：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">False</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span>
<span class="go">{}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-initial-form-values">
<span id="s-ref-forms-initial-form-values"></span><span id="initial-form-values"></span><span id="ref-forms-initial-form-values"></span><h2>初始表单值<a class="headerlink" href="#initial-form-values" title="永久链接至标题">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.initial">
<code class="descclassname">Form.</code><code class="descname">initial</code><a class="headerlink" href="#django.forms.Form.initial" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>使用 <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> 在运行时声明表单字段的初始值。例如，你可能想用当前会话的用户名来填写 <code class="docutils literal notranslate"><span class="pre">username</span></code> 字段。</p>
<p>要实现这一目标，请使用 <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> 参数到 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a>。如果给定这个参数，它应该是一个将字段名映射到初始值的字典。只包含你要指定初始值的字段，没有必要包含表单中的每个字段。例如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there!&#39;</span><span class="p">})</span>
</pre></div>
</div>
<p>这些值只对未绑定的表单显示，如果没有提供特定的值，它们不会被用作后备值。</p>
<p>如果一个 <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> 定义了 <a class="reference internal" href="fields.html#django.forms.Field.initial" title="django.forms.Field.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> <em>并且</em> 你在实例化 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 时包含了 <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a>，那么后者 <code class="docutils literal notranslate"><span class="pre">initial</span></code> 将具有优先权。在这个例子中，<code class="docutils literal notranslate"><span class="pre">initial</span></code> 既在字段级别又在表单实例级别提供，后者具有优先权：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="s1">&#39;class&#39;</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s1">&#39;instance&#39;</span><span class="p">},</span> <span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;name&quot; value=&quot;instance&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;url&quot; name=&quot;url&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;comment&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
<dl class="method">
<dt id="django.forms.Form.get_initial_for_field">
<code class="descclassname">Form.</code><code class="descname">get_initial_for_field</code>(<em>field</em>, <em>field_name</em>)<a class="headerlink" href="#django.forms.Form.get_initial_for_field" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>返回一个表单字段的初始数据。如果存在的话，它从 <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.initial</span></code></a> 检索数据，否则尝试 <a class="reference internal" href="fields.html#django.forms.Field.initial" title="django.forms.Field.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Field.initial</span></code></a>。可调用的值将被执行。</p>
<p>我们推荐使用 <a class="reference internal" href="#django.forms.BoundField.initial" title="django.forms.BoundField.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">BoundField.initial</span></code></a> 而不是 <a class="reference internal" href="#django.forms.Form.get_initial_for_field" title="django.forms.Form.get_initial_for_field"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_initial_for_field()</span></code></a> 因为 <cite>BoundField.initial</cite> 有一个更简单的接口。另外，不像 <a class="reference internal" href="#django.forms.Form.get_initial_for_field" title="django.forms.Form.get_initial_for_field"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_initial_for_field()</span></code></a>， <a class="reference internal" href="#django.forms.BoundField.initial" title="django.forms.BoundField.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">BoundField.initial</span></code></a> 会缓存它的值。这在处理返回值是可能改变的可调用对象时尤其有用（例如，<code class="docutils literal notranslate"><span class="pre">datetime.now</span></code> 或 <code class="docutils literal notranslate"><span class="pre">uuid.uuid4</span></code>）：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">uuid</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">UUIDCommentForm</span><span class="p">(</span><span class="n">CommentForm</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">identifier</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">UUIDField</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">UUIDCommentForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">get_initial_for_field</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">fields</span><span class="p">[</span><span class="s1">&#39;identifier&#39;</span><span class="p">],</span> <span class="s1">&#39;identifier&#39;</span><span class="p">)</span>
<span class="go">UUID(&#39;972ca9e4-7bfe-4f5b-af7d-07b3aa306334&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">get_initial_for_field</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">fields</span><span class="p">[</span><span class="s1">&#39;identifier&#39;</span><span class="p">],</span> <span class="s1">&#39;identifier&#39;</span><span class="p">)</span>
<span class="go">UUID(&#39;1b411fab-844e-4dec-bd4f-e9b0495f04d0&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Using BoundField.initial, for comparison</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;identifier&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">initial</span>
<span class="go">UUID(&#39;28a09c59-5f00-4ed9-9179-a3b074fa9c30&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;identifier&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">initial</span>
<span class="go">UUID(&#39;28a09c59-5f00-4ed9-9179-a3b074fa9c30&#39;)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-checking-which-form-data-has-changed">
<span id="checking-which-form-data-has-changed"></span><h2>检查哪些表格数据已经改变<a class="headerlink" href="#checking-which-form-data-has-changed" title="永久链接至标题">¶</a></h2>
<dl class="method">
<dt id="django.forms.Form.has_changed">
<code class="descclassname">Form.</code><code class="descname">has_changed</code>()<a class="headerlink" href="#django.forms.Form.has_changed" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>当你需要检查表单数据是否与初始数据发生变化时，请使用 <code class="docutils literal notranslate"><span class="pre">has_changed()</span></code> 方法。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hello&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;foo@example.com&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">has_changed</span><span class="p">()</span>
<span class="go">False</span>
</pre></div>
</div>
<p>当表单提交后，我们会重新构建表单，并提供原始数据，以便进行对比。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">has_changed</span><span class="p">()</span>
</pre></div>
</div>
<p>如果来自 <code class="docutils literal notranslate"><span class="pre">request.POST</span></code> 的数据与 <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> 中提供的数据不同，那么 <code class="docutils literal notranslate"><span class="pre">has_changed()</span></code> 将为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，否则为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。结果是通过调用 <a class="reference internal" href="fields.html#django.forms.Field.has_changed" title="django.forms.Field.has_changed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Field.has_changed()</span></code></a> 对表单中的每个字段进行计算。</p>
<dl class="attribute">
<dt id="django.forms.Form.changed_data">
<code class="descclassname">Form.</code><code class="descname">changed_data</code><a class="headerlink" href="#django.forms.Form.changed_data" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p><code class="docutils literal notranslate"><span class="pre">changed_data</span></code> 属性返回表单绑定数据（通常是 <code class="docutils literal notranslate"><span class="pre">request.POST</span></code>）中与 <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> 中提供的数据不同的字段名列表。如果没有不同的数据，则返回一个空列表。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">if</span> <span class="n">f</span><span class="o">.</span><span class="n">has_changed</span><span class="p">():</span>
<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;The following fields changed: </span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">changed_data</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">changed_data</span>
<span class="go">[&#39;subject&#39;, &#39;message&#39;]</span>
</pre></div>
</div>
</div>
<div class="section" id="s-accessing-the-fields-from-the-form">
<span id="accessing-the-fields-from-the-form"></span><h2>访问表单中的字段<a class="headerlink" href="#accessing-the-fields-from-the-form" title="永久链接至标题">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.fields">
<code class="descclassname">Form.</code><code class="descname">fields</code><a class="headerlink" href="#django.forms.Form.fields" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>你可以从 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例的 <code class="docutils literal notranslate"><span class="pre">fields</span></code> 属性中访问其字段：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">f</span><span class="o">.</span><span class="n">fields</span><span class="o">.</span><span class="n">values</span><span class="p">():</span> <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">&lt;django.forms.fields.CharField object at 0x7ffaac632510&gt;</span>
<span class="go">&lt;django.forms.fields.URLField object at 0x7ffaac632f90&gt;</span>
<span class="go">&lt;django.forms.fields.CharField object at 0x7ffaac3aa050&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">fields</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]</span>
<span class="go">&lt;django.forms.fields.CharField object at 0x7ffaac6324d0&gt;</span>
</pre></div>
</div>
<p>你可以改变 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例的字段，以改变它在表单中的显示方式：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">&#39;&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input name=&quot;name&quot; type=&quot;text&quot; value=&quot;instance&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">fields</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">label</span> <span class="o">=</span> <span class="s2">&quot;Username&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">&#39;&lt;tr&gt;&lt;th&gt;Username:&lt;/th&gt;&lt;td&gt;&lt;input name=&quot;name&quot; type=&quot;text&quot; value=&quot;instance&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;&#39;</span>
</pre></div>
</div>
<p>请注意不要修改 <code class="docutils literal notranslate"><span class="pre">base_fields</span></code> 属性，因为这个修改会影响同一 Python 进程中所有后续的 <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> 实例：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">base_fields</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">label</span> <span class="o">=</span> <span class="s2">&quot;Username&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">another_f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">another_f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">&#39;&lt;tr&gt;&lt;th&gt;Username:&lt;/th&gt;&lt;td&gt;&lt;input name=&quot;name&quot; type=&quot;text&quot; value=&quot;class&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-accessing-clean-data">
<span id="accessing-clean-data"></span><h2>访问“干净的”数据<a class="headerlink" href="#accessing-clean-data" title="永久链接至标题">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.cleaned_data">
<code class="descclassname">Form.</code><code class="descname">cleaned_data</code><a class="headerlink" href="#django.forms.Form.cleaned_data" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p><a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 类中的每个字段不仅负责验证数据，还负责“清理”数据——将其规范为一致的格式。这是一个很好的功能，因为它允许以各种方式输入特定字段的数据，并总是产生一致的输出。</p>
<p>例如， <a class="reference internal" href="fields.html#django.forms.DateField" title="django.forms.DateField"><code class="xref py py-class docutils literal notranslate"><span class="pre">DateField</span></code></a> 将输入规范化为 Python 的 <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code> 对象。无论你传递给它的是格式为 <code class="docutils literal notranslate"><span class="pre">'1994-07-15'</span></code> 的字符串，还是 <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code> 对象，或者其他一些格式，只要它是有效的，<code class="docutils literal notranslate"><span class="pre">DateField</span></code> 都会将它规范化为 <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code> 对象。</p>
<p>当你用一组数据创建了一个 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例并对其进行验证后，你就可以通过它的 <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> 属性来访问干净的数据：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hello&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;foo@example.com&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">cleaned_data</span>
<span class="go">{&#39;cc_myself&#39;: True, &#39;message&#39;: &#39;Hi there&#39;, &#39;sender&#39;: &#39;foo@example.com&#39;, &#39;subject&#39;: &#39;hello&#39;}</span>
</pre></div>
</div>
<p>请注意，任何基于文本的字段——如 <code class="docutils literal notranslate"><span class="pre">CharField</span></code> 或 <code class="docutils literal notranslate"><span class="pre">EmailField</span></code>——总是将输入清理成一个字符串。我们将在本文档后面介绍编码的含义。</p>
<p>如果你的数据 <em>没有</em> 验证，<code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> 字典只包含有效字段：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;invalid email address&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">False</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">cleaned_data</span>
<span class="go">{&#39;cc_myself&#39;: True, &#39;message&#39;: &#39;Hi there&#39;}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> 总是只包含 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 中定义的字段的键，即使你在定义 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 时传递了额外的数据。在这个例子中，我们传递了一堆额外的字段给 <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> 构造函数，但是 <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> 只包含了表单的字段：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hello&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;foo@example.com&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;extra_field_1&#39;</span><span class="p">:</span> <span class="s1">&#39;foo&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;extra_field_2&#39;</span><span class="p">:</span> <span class="s1">&#39;bar&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;extra_field_3&#39;</span><span class="p">:</span> <span class="s1">&#39;baz&#39;</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">cleaned_data</span> <span class="c1"># Doesn&#39;t contain extra_field_1, etc.</span>
<span class="go">{&#39;cc_myself&#39;: True, &#39;message&#39;: &#39;Hi there&#39;, &#39;sender&#39;: &#39;foo@example.com&#39;, &#39;subject&#39;: &#39;hello&#39;}</span>
</pre></div>
</div>
<p>当 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 有效时，<code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> 将包括 <em>所有</em> 字段的键和值，即使数据没有包括一些可选字段的值。在这个例子中，数据字典没有包含 <code class="docutils literal notranslate"><span class="pre">nick_name</span></code> 字段的值，但 <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> 包含了它，并使用一个空值：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">OptionalPersonForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">first_name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">last_name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">nick_name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;first_name&#39;</span><span class="p">:</span> <span class="s1">&#39;John&#39;</span><span class="p">,</span> <span class="s1">&#39;last_name&#39;</span><span class="p">:</span> <span class="s1">&#39;Lennon&#39;</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">OptionalPersonForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">cleaned_data</span>
<span class="go">{&#39;nick_name&#39;: &#39;&#39;, &#39;first_name&#39;: &#39;John&#39;, &#39;last_name&#39;: &#39;Lennon&#39;}</span>
</pre></div>
</div>
<p>在上面这个例子中，<code class="docutils literal notranslate"><span class="pre">nick_name</span></code> 的 <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> 值被设置为一个空字符串，因为 <code class="docutils literal notranslate"><span class="pre">nick_name</span></code> 是 <code class="docutils literal notranslate"><span class="pre">CharField</span></code>，而 <code class="docutils literal notranslate"><span class="pre">CharField</span></code> 将空值视为空字符串。每个字段类型都知道它的“空”值是什么——例如，对于 <code class="docutils literal notranslate"><span class="pre">DateField</span></code>，它是 <code class="docutils literal notranslate"><span class="pre">None</span></code> 而不是空字符串。关于每个字段在这种情况下的行为的全部细节，请参阅下面“内置 <code class="docutils literal notranslate"><span class="pre">Field</span></code> 类”一节中每个字段的“空值”说明。</p>
<p>你可以编写代码来对特定的表单字段（基于其名称）或整个表单（考虑各种字段的组合）进行验证。更多关于这方面的信息请参见 <a class="reference internal" href="validation.html"><span class="doc">表单和字段验证</span></a>。</p>
</div>
<div class="section" id="s-outputting-forms-as-html">
<span id="s-ref-forms-api-outputting-html"></span><span id="outputting-forms-as-html"></span><span id="ref-forms-api-outputting-html"></span><h2>将表单输出为 HTML<a class="headerlink" href="#outputting-forms-as-html" title="永久链接至标题">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">Form</span></code> 对象的第二个任务是将其本身渲染为 HTML。为此，<code class="docutils literal notranslate"><span class="pre">print</span></code> 对象：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot;&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
<p>如果表单与数据绑定，HTML 输出将适当地包含该数据。例如，如果一个字段用 <code class="docutils literal notranslate"><span class="pre">&lt;input</span> <span class="pre">type=&quot;text&quot;&gt;</span></code> 表示，数据将在 <code class="docutils literal notranslate"><span class="pre">value</span></code> 属性中。如果一个字段用 <code class="docutils literal notranslate"><span class="pre">&lt;input</span> <span class="pre">type=&quot;checkbox&quot;&gt;</span></code> 表示，那么 HTML 将适当地包括 <code class="docutils literal notranslate"><span class="pre">checked</span></code>：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hello&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;foo@example.com&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; value=&quot;hello&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; value=&quot;Hi there&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; value=&quot;foo@example.com&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot; checked&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
<p>这个默认输出是一个两列的 HTML 表单，每个字段都有一个 <code class="docutils literal notranslate"><span class="pre">&lt;tr&gt;</span></code>。请注意以下几点：</p>
<ul class="simple">
<li>为灵活起见，输出 <em>不</em> 包括 <code class="docutils literal notranslate"><span class="pre">&lt;table&gt;</span></code> 和 <code class="docutils literal notranslate"><span class="pre">&lt;/table&gt;</span></code> 标签，也不包括 <code class="docutils literal notranslate"><span class="pre">&lt;form&gt;</span></code> 和 <code class="docutils literal notranslate"><span class="pre">&lt;/form&gt;</span></code> 标签或 <code class="docutils literal notranslate"><span class="pre">&lt;input</span> <span class="pre">type=&quot;submit&quot;&gt;</span></code> 标签。这是你的工作。</li>
<li>每个字段类型都有一个默认的 HTML 表示。<code class="docutils literal notranslate"><span class="pre">CharField</span></code> 用 <code class="docutils literal notranslate"><span class="pre">&lt;input</span> <span class="pre">type=&quot;text&quot;&gt;</span></code> 表示，<code class="docutils literal notranslate"><span class="pre">EmailField</span></code> 用 <code class="docutils literal notranslate"><span class="pre">&lt;input</span> <span class="pre">type=&quot;email&quot;&gt;</span></code> 表示。<code class="docutils literal notranslate"><span class="pre">BooleanField(null=False)</span></code> 由一个 <code class="docutils literal notranslate"><span class="pre">&lt;input</span> <span class="pre">type=&quot;checkbox&quot;&gt;</span></code>。请注意，这些只是合理的默认值；你可以通过使用部件来指定一个给定字段使用的 HTML，我们将在后面解释。</li>
<li>每个标签的 HTML <code class="docutils literal notranslate"><span class="pre">name</span></code> 直接从 <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> 类中的属性名中提取。</li>
<li>每个字段的文本标签——例如 <code class="docutils literal notranslate"><span class="pre">'Subject:'</span></code>、<code class="docutils literal notranslate"><span class="pre">'Message:'</span></code> 和 <code class="docutils literal notranslate"><span class="pre">'Cc</span> <span class="pre">myself:'</span></code>，是根据字段名将所有下划线转换为空格并将第一个字母大写而产生的。同样，请注意这些只是合理的默认值；你也可以手动指定标签。</li>
<li>每个文本标签都被一个 HTML <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签包围，该标签通过其 <code class="docutils literal notranslate"><span class="pre">id</span></code> 指向相应的表格字段。而它的 <code class="docutils literal notranslate"><span class="pre">id</span></code> 则是通过在字段名前加上 <code class="docutils literal notranslate"><span class="pre">'id_'</span></code> 生成的。<code class="docutils literal notranslate"><span class="pre">id</span></code> 属性和 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签默认包含在输出中，以遵循最佳实践，但你可以改变这种行为。</li>
<li>输出使用 HTML5 语法，目标是 <code class="docutils literal notranslate"><span class="pre">&lt;!DOCTYPE</span> <span class="pre">html&gt;</span></code>。例如，它使用布尔属性，如 <code class="docutils literal notranslate"><span class="pre">checked</span></code> 而不是 XHTML 风格的 <code class="docutils literal notranslate"><span class="pre">checked='checked'</span></code>。</li>
</ul>
<p>虽然当你 <code class="docutils literal notranslate"><span class="pre">print</span></code> 表单时，<code class="docutils literal notranslate"><span class="pre">&lt;table&gt;</span></code> 输出是默认的输出样式，但还有其他的输出样式。每种样式都可以作为表单对象的一个方法，每个渲染方法都返回一个字符串。</p>
<div class="section" id="s-as-p">
<span id="as-p"></span><h3><code class="docutils literal notranslate"><span class="pre">as_p()</span></code><a class="headerlink" href="#as-p" title="永久链接至标题">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_p">
<code class="descclassname">Form.</code><code class="descname">as_p</code>()<a class="headerlink" href="#django.forms.Form.as_p" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p><code class="docutils literal notranslate"><span class="pre">as_p()</span></code> 将表单渲染为一系列 <code class="docutils literal notranslate"><span class="pre">&lt;p&gt;</span></code> 标签，每个 <code class="docutils literal notranslate"><span class="pre">&lt;p&gt;</span></code> 包含一个字段：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">()</span>
<span class="go">&#39;&lt;p&gt;&lt;label for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt; &lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/p&gt;\n&lt;p&gt;&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;&lt;/p&gt;\n&lt;p&gt;&lt;label for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; required&gt;&lt;/p&gt;\n&lt;p&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot;&gt;&lt;/p&gt;&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt; &lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot;&gt;&lt;/p&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-as-ul">
<span id="as-ul"></span><h3><code class="docutils literal notranslate"><span class="pre">as_ul()</span></code><a class="headerlink" href="#as-ul" title="永久链接至标题">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_ul">
<code class="descclassname">Form.</code><code class="descname">as_ul</code>()<a class="headerlink" href="#django.forms.Form.as_ul" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p><code class="docutils literal notranslate"><span class="pre">as_ul()</span></code> 将表单渲染为一系列 <code class="docutils literal notranslate"><span class="pre">&lt;li&gt;</span></code> 标签，每个 <code class="docutils literal notranslate"><span class="pre">&lt;li&gt;</span></code> 包含一个字段。它并 <em>不</em> 包括 <code class="docutils literal notranslate"><span class="pre">&lt;ul&gt;</span></code> 或 <code class="docutils literal notranslate"><span class="pre">&lt;/ul&gt;</span></code>，因此你可以在 <code class="docutils literal notranslate"><span class="pre">&lt;ul&gt;</span></code> 上指定任何 HTML 属性，以提高灵活性：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">()</span>
<span class="go">&#39;&lt;li&gt;&lt;label for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt; &lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;\n&lt;li&gt;&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;&lt;/li&gt;\n&lt;li&gt;&lt;label for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; required&gt;&lt;/li&gt;\n&lt;li&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot;&gt;&lt;/li&gt;&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt; &lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot;&gt;&lt;/li&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-as-table">
<span id="as-table"></span><h3><code class="docutils literal notranslate"><span class="pre">as_table()</span></code><a class="headerlink" href="#as-table" title="永久链接至标题">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_table">
<code class="descclassname">Form.</code><code class="descname">as_table</code>()<a class="headerlink" href="#django.forms.Form.as_table" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>最后，<code class="docutils literal notranslate"><span class="pre">as_table()</span></code> 将表单输出为 HTML <code class="docutils literal notranslate"><span class="pre">&lt;table&gt;</span></code>。这和 <code class="docutils literal notranslate"><span class="pre">print</span></code> 完全一样。事实上，当你 <code class="docutils literal notranslate"><span class="pre">print</span></code> 一个表单对象时，它在幕后调用了它的 <code class="docutils literal notranslate"><span class="pre">as_table()</span></code> 方法：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span>
<span class="go">&#39;&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;\n&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;\n&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;\n&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot;&gt;&lt;/td&gt;&lt;/tr&gt;&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot;&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-styling-required-or-erroneous-form-rows">
<span id="s-ref-forms-api-styling-form-rows"></span><span id="styling-required-or-erroneous-form-rows"></span><span id="ref-forms-api-styling-form-rows"></span><h3>样式化必填或错误的表单行<a class="headerlink" href="#styling-required-or-erroneous-form-rows" title="永久链接至标题">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Form.error_css_class">
<code class="descclassname">Form.</code><code class="descname">error_css_class</code><a class="headerlink" href="#django.forms.Form.error_css_class" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="django.forms.Form.required_css_class">
<code class="descclassname">Form.</code><code class="descname">required_css_class</code><a class="headerlink" href="#django.forms.Form.required_css_class" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>对必填或有错误的表单行和字段进行样式设计是很常见的。例如，你可能想用粗体显示必填的表格行，用红色突出显示错误。</p>
<p><a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 类有几个钩子，你可以用来给必填行或有错误的行添加 <code class="docutils literal notranslate"><span class="pre">class</span></code> 属性：设置 <a class="reference internal" href="#django.forms.Form.error_css_class" title="django.forms.Form.error_css_class"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.error_css_class</span></code></a> 和／或 <a class="reference internal" href="#django.forms.Form.required_css_class" title="django.forms.Form.required_css_class"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.required_css_class</span></code></a> 属性：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>

<span class="k">class</span> <span class="nc">ContactForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">error_css_class</span> <span class="o">=</span> <span class="s1">&#39;error&#39;</span>
    <span class="n">required_css_class</span> <span class="o">=</span> <span class="s1">&#39;required&#39;</span>

    <span class="c1"># ... and the rest of your fields here</span>
</pre></div>
</div>
<p>一旦你这样做了，根据需要，行将被赋予 <code class="docutils literal notranslate"><span class="pre">&quot;error&quot;</span></code> 和／或 <code class="docutils literal notranslate"><span class="pre">&quot;required&quot;</span></code> 类。HTML 将看起来像：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">())</span>
<span class="go">&lt;tr class=&quot;required&quot;&gt;&lt;th&gt;&lt;label class=&quot;required&quot; for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt;    ...</span>
<span class="go">&lt;tr class=&quot;required&quot;&gt;&lt;th&gt;&lt;label class=&quot;required&quot; for=&quot;id_message&quot;&gt;Message:&lt;/label&gt;    ...</span>
<span class="go">&lt;tr class=&quot;required error&quot;&gt;&lt;th&gt;&lt;label class=&quot;required&quot; for=&quot;id_sender&quot;&gt;Sender:&lt;/label&gt;      ...</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_cc_myself&quot;&gt;Cc myself:&lt;label&gt; ...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">label_tag</span><span class="p">()</span>
<span class="go">&lt;label class=&quot;required&quot; for=&quot;id_subject&quot;&gt;Subject:&lt;/label&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">label_tag</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;foo&#39;</span><span class="p">})</span>
<span class="go">&lt;label for=&quot;id_subject&quot; class=&quot;foo required&quot;&gt;Subject:&lt;/label&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-configuring-form-elements-html-id-attributes-and-label-tags">
<span id="s-ref-forms-api-configuring-label"></span><span id="configuring-form-elements-html-id-attributes-and-label-tags"></span><span id="ref-forms-api-configuring-label"></span><h3>设置表单元素的 HTML <code class="docutils literal notranslate"><span class="pre">id</span></code> 属性和 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签。<a class="headerlink" href="#configuring-form-elements-html-id-attributes-and-label-tags" title="永久链接至标题">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Form.auto_id">
<code class="descclassname">Form.</code><code class="descname">auto_id</code><a class="headerlink" href="#django.forms.Form.auto_id" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>默认情况下，表单渲染方法包括：</p>
<ul class="simple">
<li>表单元素的 HTML <code class="docutils literal notranslate"><span class="pre">id</span></code> 属性。</li>
<li>标签周围对应的 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签。HTML <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签指定了哪个标签文本与哪个表单元素相关联。这个小小的改进使表单更加可用，也更容易被辅助设备访问。使用 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签总是一个好主意。</li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">id</span></code> 属性值是通过将 <code class="docutils literal notranslate"><span class="pre">id_</span></code> 预置到表单字段名后生成的。 如果你想改变 <code class="docutils literal notranslate"><span class="pre">id</span></code> 惯例或完全删除 HTML <code class="docutils literal notranslate"><span class="pre">id</span></code> 属性和 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签，这种行为是可以设置的。</p>
<p>使用 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 构造函数的 <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> 参数来控制 <code class="docutils literal notranslate"><span class="pre">id</span></code> 和标签行为。这个参数必须是 <code class="docutils literal notranslate"><span class="pre">True</span></code>、<code class="docutils literal notranslate"><span class="pre">False</span></code> 或一个字符串。</p>
<p>如果 <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code>，那么表单输出将不包含 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签或 <code class="docutils literal notranslate"><span class="pre">id</span></code> 属性：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">())</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Subject:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Message:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;message&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Sender:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;email&quot; name=&quot;sender&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Cc myself:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot;&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;Subject: &lt;input type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Message: &lt;input type=&quot;text&quot; name=&quot;message&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Sender: &lt;input type=&quot;email&quot; name=&quot;sender&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Cc myself: &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot;&gt;&lt;/li&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go">&lt;p&gt;Subject: &lt;input type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Message: &lt;input type=&quot;text&quot; name=&quot;message&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Sender: &lt;input type=&quot;email&quot; name=&quot;sender&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Cc myself: &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot;&gt;&lt;/p&gt;</span>
</pre></div>
</div>
<p>如果 <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> 设置为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，那么表单输出 <em>将</em> 包括 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签，并将使用字段名作为每个表单字段的 <code class="docutils literal notranslate"><span class="pre">id</span></code>：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">())</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;subject&quot;&gt;Subject:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input id=&quot;subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;message&quot;&gt;Message:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;message&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;sender&quot;&gt;Sender:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;sender&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;cc_myself&quot;&gt;Cc myself:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;cc_myself&quot;&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;subject&quot;&gt;Subject:&lt;/label&gt; &lt;input id=&quot;subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;message&quot;&gt;Message:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;message&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;sender&quot;&gt;Sender:&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;sender&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;cc_myself&quot;&gt;Cc myself:&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;cc_myself&quot;&gt;&lt;/li&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;subject&quot;&gt;Subject:&lt;/label&gt; &lt;input id=&quot;subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;message&quot;&gt;Message:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;message&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;sender&quot;&gt;Sender:&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;sender&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;cc_myself&quot;&gt;Cc myself:&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;cc_myself&quot;&gt;&lt;/p&gt;</span>
</pre></div>
</div>
<p>如果 <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> 被设置为包含格式字符 <code class="docutils literal notranslate"><span class="pre">'%s'</span></code> 的字符串，那么表单输出将包含 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签，并将根据格式字符串生成 <code class="docutils literal notranslate"><span class="pre">id</span></code> 属性。例如，对于格式字符串 <code class="docutils literal notranslate"><span class="pre">'field_%s'</span></code>，名为 <code class="docutils literal notranslate"><span class="pre">subject</span></code> 的字段将得到 <code class="docutils literal notranslate"><span class="pre">id</span></code> 值 <code class="docutils literal notranslate"><span class="pre">'field_subject'</span></code>。继续我们的例子：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="s1">&#39;id_for_</span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">())</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_for_subject&quot;&gt;Subject:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input id=&quot;id_for_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_for_message&quot;&gt;Message:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_for_message&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_for_sender&quot;&gt;Sender:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_for_sender&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;&lt;label for=&quot;id_for_cc_myself&quot;&gt;Cc myself:&lt;/label&gt;&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_for_cc_myself&quot;&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_subject&quot;&gt;Subject:&lt;/label&gt; &lt;input id=&quot;id_for_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_message&quot;&gt;Message:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_for_message&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_sender&quot;&gt;Sender:&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_for_sender&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_cc_myself&quot;&gt;Cc myself:&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_for_cc_myself&quot;&gt;&lt;/li&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;id_for_subject&quot;&gt;Subject:&lt;/label&gt; &lt;input id=&quot;id_for_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;id_for_message&quot;&gt;Message:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_for_message&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;id_for_sender&quot;&gt;Sender:&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_for_sender&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;label for=&quot;id_for_cc_myself&quot;&gt;Cc myself:&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_for_cc_myself&quot;&gt;&lt;/p&gt;</span>
</pre></div>
</div>
<p>如果 <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> 被设置为任何其他的真值——比如一个不包含 <code class="docutils literal notranslate"><span class="pre">%s</span></code> 的字符串——那么该库就会像 <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> 是 <code class="docutils literal notranslate"><span class="pre">True</span></code> 一样。</p>
<p>默认情况下，<code class="docutils literal notranslate"><span class="pre">auto_id</span></code> 被设置为字符串 <code class="docutils literal notranslate"><span class="pre">'id_%s'</span></code>。</p>
<dl class="attribute">
<dt id="django.forms.Form.label_suffix">
<code class="descclassname">Form.</code><code class="descname">label_suffix</code><a class="headerlink" href="#django.forms.Form.label_suffix" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>一个可翻译的字符串（英文默认为冒号（<code class="docutils literal notranslate"><span class="pre">:</span></code>）），将在渲染表格时附加在任何标签名称之后。</p>
<p>可以使用 <code class="docutils literal notranslate"><span class="pre">label_suffix</span></code> 参数自定义该字符，或者完全省略：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="s1">&#39;id_for_</span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">label_suffix</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_subject&quot;&gt;Subject&lt;/label&gt; &lt;input id=&quot;id_for_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_message&quot;&gt;Message&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_for_message&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_sender&quot;&gt;Sender&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_for_sender&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_cc_myself&quot;&gt;Cc myself&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_for_cc_myself&quot;&gt;&lt;/li&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="s1">&#39;id_for_</span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">label_suffix</span><span class="o">=</span><span class="s1">&#39; -&gt;&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_subject&quot;&gt;Subject -&gt;&lt;/label&gt; &lt;input id=&quot;id_for_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_message&quot;&gt;Message -&gt;&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_for_message&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_sender&quot;&gt;Sender -&gt;&lt;/label&gt; &lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_for_sender&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_for_cc_myself&quot;&gt;Cc myself -&gt;&lt;/label&gt; &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_for_cc_myself&quot;&gt;&lt;/li&gt;</span>
</pre></div>
</div>
<p>请注意，只有当标签的最后一个字符不是标点符号时，才会加上标签后缀（在英文中，这些字符是 <code class="docutils literal notranslate"><span class="pre">.</span></code>、<code class="docutils literal notranslate"><span class="pre">!</span></code>、<code class="docutils literal notranslate"><span class="pre">?</span></code> 或 <code class="docutils literal notranslate"><span class="pre">:</span></code>）。</p>
<p>字段也可以定义自己的 <a class="reference internal" href="fields.html#django.forms.Field.label_suffix" title="django.forms.Field.label_suffix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">label_suffix</span></code></a>。这将优先于 <a class="reference internal" href="#django.forms.Form.label_suffix" title="django.forms.Form.label_suffix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.label_suffix</span></code></a>。后缀也可以在运行时使用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">label_suffix()</span></code> 参数来覆盖。</p>
<dl class="attribute">
<dt id="django.forms.Form.use_required_attribute">
<code class="descclassname">Form.</code><code class="descname">use_required_attribute</code><a class="headerlink" href="#django.forms.Form.use_required_attribute" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>当设置为 <code class="docutils literal notranslate"><span class="pre">True</span></code> （默认）时，必填表单字段将有 <code class="docutils literal notranslate"><span class="pre">required</span></code> HTML 属性。</p>
<p><a class="reference internal" href="../../topics/forms/formsets.html"><span class="doc">表单集</span></a> 实例化表单时使用 <code class="docutils literal notranslate"><span class="pre">use_required_attribute=False</span></code> 以避免从表单集中添加和删除表单时浏览器验证错误。</p>
</div>
<div class="section" id="s-configuring-the-rendering-of-a-form-s-widgets">
<span id="configuring-the-rendering-of-a-form-s-widgets"></span><h3>设置表单组件的渲染方式<a class="headerlink" href="#configuring-the-rendering-of-a-form-s-widgets" title="永久链接至标题">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Form.default_renderer">
<code class="descclassname">Form.</code><code class="descname">default_renderer</code><a class="headerlink" href="#django.forms.Form.default_renderer" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>指定 <a class="reference internal" href="renderers.html"><span class="doc">渲染器</span></a> 用于表单的渲染。默认值为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，表示使用 <a class="reference internal" href="../settings.html#std:setting-FORM_RENDERER"><code class="xref std std-setting docutils literal notranslate"><span class="pre">FORM_RENDERER</span></code></a> 设置中指定的默认渲染器。</p>
<p>你可以在声明你的表单时将其设置为一个类属性，或者使用 <code class="docutils literal notranslate"><span class="pre">Form.__init__()</span></code> 的 <code class="docutils literal notranslate"><span class="pre">renderer</span></code> 参数。例如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>

<span class="k">class</span> <span class="nc">MyForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">default_renderer</span> <span class="o">=</span> <span class="n">MyRenderer</span><span class="p">()</span>
</pre></div>
</div>
<p>或者：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">form</span> <span class="o">=</span> <span class="n">MyForm</span><span class="p">(</span><span class="n">renderer</span><span class="o">=</span><span class="n">MyRenderer</span><span class="p">())</span>
</pre></div>
</div>
</div>
<div class="section" id="s-notes-on-field-ordering">
<span id="notes-on-field-ordering"></span><h3>字段顺序的注意事项<a class="headerlink" href="#notes-on-field-ordering" title="永久链接至标题">¶</a></h3>
<p>在 <code class="docutils literal notranslate"><span class="pre">as_p()</span></code>、<code class="docutils literal notranslate"><span class="pre">as_ul()</span></code> 和 <code class="docutils literal notranslate"><span class="pre">as_table()</span></code> 快捷方式中，字段是按照你在表单类中定义的顺序显示的。例如，在 <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> 的例子中，字段是按照 <code class="docutils literal notranslate"><span class="pre">subject</span></code>、<code class="docutils literal notranslate"><span class="pre">message</span></code>、<code class="docutils literal notranslate"><span class="pre">sender</span></code>、<code class="docutils literal notranslate"><span class="pre">cc_myself</span></code> 的顺序定义的。要调整 HTML 输出的顺序，改变这些字段在类中的排列顺序。</p>
<p>还有其他几种方式可以自定义顺序：</p>
<dl class="attribute">
<dt id="django.forms.Form.field_order">
<code class="descclassname">Form.</code><code class="descname">field_order</code><a class="headerlink" href="#django.forms.Form.field_order" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>默认情况下 <code class="docutils literal notranslate"><span class="pre">Form.field_order=None</span></code>，它保留了你在表单类中定义字段的顺序。如果 <code class="docutils literal notranslate"><span class="pre">field_order</span></code> 是一个字段名的列表，则字段按列表指定的顺序排列，其余字段按默认顺序追加。列表中未知的字段名将被忽略。这使得在子类中可以通过将字段设置为 <code class="docutils literal notranslate"><span class="pre">None</span></code> 来禁用字段，而不必重新定义排序。</p>
<p>你也可以使用 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 的 <code class="docutils literal notranslate"><span class="pre">Form.field_order</span></code> 参数来覆盖字段顺序。如果一个 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 定义了 <a class="reference internal" href="#django.forms.Form.field_order" title="django.forms.Form.field_order"><code class="xref py py-attr docutils literal notranslate"><span class="pre">field_order</span></code></a>，<em>并且</em> 你在实例化 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 时包含了 <code class="docutils literal notranslate"><span class="pre">field_order</span></code>，那么后者的 <code class="docutils literal notranslate"><span class="pre">field_order</span></code> 将具有优先权。</p>
<dl class="method">
<dt id="django.forms.Form.order_fields">
<code class="descclassname">Form.</code><code class="descname">order_fields</code>(<em>field_order</em>)<a class="headerlink" href="#django.forms.Form.order_fields" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>你可以在任何时候使用 <code class="docutils literal notranslate"><span class="pre">order_fields()</span></code> 对字段进行重新排列，字段名列表如 <a class="reference internal" href="#django.forms.Form.field_order" title="django.forms.Form.field_order"><code class="xref py py-attr docutils literal notranslate"><span class="pre">field_order</span></code></a>。</p>
</div>
<div class="section" id="s-how-errors-are-displayed">
<span id="how-errors-are-displayed"></span><h3>如何显示错误<a class="headerlink" href="#how-errors-are-displayed" title="永久链接至标题">¶</a></h3>
<p>如果你渲染一个绑定的 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 对象，渲染行为将自动运行表单的验证，如果它还没有发生，HTML 输出将包括验证错误，作为字段附近的 <code class="docutils literal notranslate"><span class="pre">&lt;ul</span> <span class="pre">class=&quot;errorlist&quot;&gt;</span></code>。错误信息的具体位置取决于你使用的输出方法：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;invalid email address&#39;</span><span class="p">,</span>
<span class="gp">... </span>        <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">())</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Subject:&lt;/th&gt;&lt;td&gt;&lt;ul class=&quot;errorlist&quot;&gt;&lt;li&gt;This field is required.&lt;/li&gt;&lt;/ul&gt;&lt;input type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Message:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;message&quot; value=&quot;Hi there&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Sender:&lt;/th&gt;&lt;td&gt;&lt;ul class=&quot;errorlist&quot;&gt;&lt;li&gt;Enter a valid email address.&lt;/li&gt;&lt;/ul&gt;&lt;input type=&quot;email&quot; name=&quot;sender&quot; value=&quot;invalid email address&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Cc myself:&lt;/th&gt;&lt;td&gt;&lt;input checked type=&quot;checkbox&quot; name=&quot;cc_myself&quot;&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;&lt;ul class=&quot;errorlist&quot;&gt;&lt;li&gt;This field is required.&lt;/li&gt;&lt;/ul&gt;Subject: &lt;input type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Message: &lt;input type=&quot;text&quot; name=&quot;message&quot; value=&quot;Hi there&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;ul class=&quot;errorlist&quot;&gt;&lt;li&gt;Enter a valid email address.&lt;/li&gt;&lt;/ul&gt;Sender: &lt;input type=&quot;email&quot; name=&quot;sender&quot; value=&quot;invalid email address&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Cc myself: &lt;input checked type=&quot;checkbox&quot; name=&quot;cc_myself&quot;&gt;&lt;/li&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go">&lt;p&gt;&lt;ul class=&quot;errorlist&quot;&gt;&lt;li&gt;This field is required.&lt;/li&gt;&lt;/ul&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Subject: &lt;input type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Message: &lt;input type=&quot;text&quot; name=&quot;message&quot; value=&quot;Hi there&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;&lt;ul class=&quot;errorlist&quot;&gt;&lt;li&gt;Enter a valid email address.&lt;/li&gt;&lt;/ul&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Sender: &lt;input type=&quot;email&quot; name=&quot;sender&quot; value=&quot;invalid email address&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Cc myself: &lt;input checked type=&quot;checkbox&quot; name=&quot;cc_myself&quot;&gt;&lt;/p&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-customizing-the-error-list-format">
<span id="s-ref-forms-error-list-format"></span><span id="customizing-the-error-list-format"></span><span id="ref-forms-error-list-format"></span><h3>自定义错误列表格式<a class="headerlink" href="#customizing-the-error-list-format" title="永久链接至标题">¶</a></h3>
<p>默认情况下，表单使用 <code class="docutils literal notranslate"><span class="pre">django.forms.utils.ErrorList</span></code> 来格式化验证错误。如果你想使用一个替代的类来显示错误，你可以在构造时传入：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django.forms.utils</span> <span class="kn">import</span> <span class="n">ErrorList</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">DivErrorList</span><span class="p">(</span><span class="n">ErrorList</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">as_divs</span><span class="p">()</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">as_divs</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span>        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="p">:</span> <span class="k">return</span> <span class="s1">&#39;&#39;</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="s1">&#39;&lt;div class=&quot;errorlist&quot;&gt;</span><span class="si">%s</span><span class="s1">&lt;/div&gt;&#39;</span> <span class="o">%</span> <span class="s1">&#39;&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="s1">&#39;&lt;div class=&quot;error&quot;&gt;</span><span class="si">%s</span><span class="s1">&lt;/div&gt;&#39;</span> <span class="o">%</span> <span class="n">e</span> <span class="k">for</span> <span class="n">e</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">error_class</span><span class="o">=</span><span class="n">DivErrorList</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">()</span>
<span class="go">&lt;div class=&quot;errorlist&quot;&gt;&lt;div class=&quot;error&quot;&gt;This field is required.&lt;/div&gt;&lt;/div&gt;</span>
<span class="go">&lt;p&gt;Subject: &lt;input type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Message: &lt;input type=&quot;text&quot; name=&quot;message&quot; value=&quot;Hi there&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;div class=&quot;errorlist&quot;&gt;&lt;div class=&quot;error&quot;&gt;Enter a valid email address.&lt;/div&gt;&lt;/div&gt;</span>
<span class="go">&lt;p&gt;Sender: &lt;input type=&quot;email&quot; name=&quot;sender&quot; value=&quot;invalid email address&quot; required&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Cc myself: &lt;input checked type=&quot;checkbox&quot; name=&quot;cc_myself&quot;&gt;&lt;/p&gt;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-more-granular-output">
<span id="more-granular-output"></span><h2>更精细的输出<a class="headerlink" href="#more-granular-output" title="永久链接至标题">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">as_p()</span></code>、<code class="docutils literal notranslate"><span class="pre">as_ul()</span></code> 和 <code class="docutils literal notranslate"><span class="pre">as_table()</span></code> 方法都是快捷方式——它们并不是显示表单对象的唯一方式。</p>
<dl class="class">
<dt id="django.forms.BoundField">
<em class="property">class </em><code class="descname">BoundField</code><a class="headerlink" href="#django.forms.BoundField" title="永久链接至目标">¶</a></dt>
<dd><p>用于显示 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例的单个字段的 HTML 或访问属性。</p>
<p>该对象的 <code class="docutils literal notranslate"><span class="pre">__str__()</span></code> 方法显示该字段的 HTML。</p>
</dd></dl>

<p>要检索一个单一的 <code class="docutils literal notranslate"><span class="pre">BoundField</span></code>，在你的表单中使用字典查询语法，使用字段名作为键：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">form</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">])</span>
<span class="go">&lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;</span>
</pre></div>
</div>
<p>要检索所有的 <code class="docutils literal notranslate"><span class="pre">BoundField</span></code> 对象，请迭代表单：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">boundfield</span> <span class="ow">in</span> <span class="n">form</span><span class="p">:</span> <span class="nb">print</span><span class="p">(</span><span class="n">boundfield</span><span class="p">)</span>
<span class="go">&lt;input id=&quot;id_subject&quot; type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;</span>
<span class="go">&lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;</span>
<span class="go">&lt;input type=&quot;email&quot; name=&quot;sender&quot; id=&quot;id_sender&quot; required&gt;</span>
<span class="go">&lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot; id=&quot;id_cc_myself&quot;&gt;</span>
</pre></div>
</div>
<p>特定字段的输出尊重表单对象的 <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> 设置：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">])</span>
<span class="go">&lt;input type=&quot;text&quot; name=&quot;message&quot; required&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="s1">&#39;id_</span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">])</span>
<span class="go">&lt;input type=&quot;text&quot; name=&quot;message&quot; id=&quot;id_message&quot; required&gt;</span>
</pre></div>
</div>
<div class="section" id="s-attributes-of-boundfield">
<span id="attributes-of-boundfield"></span><h3><code class="docutils literal notranslate"><span class="pre">BoundField</span></code> 的属性<a class="headerlink" href="#attributes-of-boundfield" title="永久链接至标题">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.BoundField.auto_id">
<code class="descclassname">BoundField.</code><code class="descname">auto_id</code><a class="headerlink" href="#django.forms.BoundField.auto_id" title="永久链接至目标">¶</a></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">BoundField</span></code> 的 HTML ID 属性。如果 <a class="reference internal" href="#django.forms.Form.auto_id" title="django.forms.Form.auto_id"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.auto_id</span></code></a> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code>，则返回一个空字符串。</p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.data">
<code class="descclassname">BoundField.</code><code class="descname">data</code><a class="headerlink" href="#django.forms.BoundField.data" title="永久链接至目标">¶</a></dt>
<dd><p>此属性返回由部件的 <a class="reference internal" href="widgets.html#django.forms.Widget.value_from_datadict" title="django.forms.Widget.value_from_datadict"><code class="xref py py-meth docutils literal notranslate"><span class="pre">value_from_datadict()</span></code></a> 方法提取的此 <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a> 的数据，如果没有给定则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">unbound_form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">unbound_form</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">data</span><span class="p">)</span>
<span class="go">None</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bound_form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;My Subject&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">bound_form</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">data</span><span class="p">)</span>
<span class="go">My Subject</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.errors">
<code class="descclassname">BoundField.</code><code class="descname">errors</code><a class="headerlink" href="#django.forms.BoundField.errors" title="永久链接至目标">¶</a></dt>
<dd><p>一个 <a class="reference internal" href="#ref-forms-error-list-format"><span class="std std-ref">类似列表的对象</span></a>，打印时显示为 HTML <code class="docutils literal notranslate"><span class="pre">&lt;ul</span> <span class="pre">class=&quot;errorlist&quot;&gt;</span></code>：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hi&#39;</span><span class="p">,</span> <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">])</span>
<span class="go">&lt;input type=&quot;text&quot; name=&quot;message&quot; required&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span>
<span class="go">[&#39;This field is required.&#39;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span><span class="p">)</span>
<span class="go">&lt;ul class=&quot;errorlist&quot;&gt;&lt;li&gt;This field is required.&lt;/li&gt;&lt;/ul&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span>
<span class="go">[]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span><span class="p">)</span>
<span class="go">&#39;&#39;</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.field">
<code class="descclassname">BoundField.</code><code class="descname">field</code><a class="headerlink" href="#django.forms.BoundField.field" title="永久链接至目标">¶</a></dt>
<dd><p>这个 <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> 封装的表单类中的表单 <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a> 实例。</p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.form">
<code class="descclassname">BoundField.</code><code class="descname">form</code><a class="headerlink" href="#django.forms.BoundField.form" title="永久链接至目标">¶</a></dt>
<dd><p>这个 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 实例与这个 <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a> 绑定。</p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.help_text">
<code class="descclassname">BoundField.</code><code class="descname">help_text</code><a class="headerlink" href="#django.forms.BoundField.help_text" title="永久链接至目标">¶</a></dt>
<dd><p>字段的 <a class="reference internal" href="fields.html#django.forms.Field.help_text" title="django.forms.Field.help_text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help_text</span></code></a>。</p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.html_name">
<code class="descclassname">BoundField.</code><code class="descname">html_name</code><a class="headerlink" href="#django.forms.BoundField.html_name" title="永久链接至目标">¶</a></dt>
<dd><p>部件的 HTML <code class="docutils literal notranslate"><span class="pre">name</span></code> 属性中使用的名称。它考虑到了 <a class="reference internal" href="#django.forms.Form.prefix" title="django.forms.Form.prefix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">prefix</span></code></a> 的形式。</p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.id_for_label">
<code class="descclassname">BoundField.</code><code class="descname">id_for_label</code><a class="headerlink" href="#django.forms.BoundField.id_for_label" title="永久链接至目标">¶</a></dt>
<dd><p>使用这个属性来渲染这个字段的 ID。例如，如果你在你的模板中手动构建一个 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> （尽管事实上 <a class="reference internal" href="#django.forms.BoundField.label_tag" title="django.forms.BoundField.label_tag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">label_tag()</span></code></a> 将为你做这件事）：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">form.my_field.id_for_label</span> <span class="cp">}}</span><span class="s">&quot;</span><span class="p">&gt;</span>...<span class="p">&lt;/</span><span class="nt">label</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">my_field</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>默认情况下，这将是字段的名称，前缀为 <code class="docutils literal notranslate"><span class="pre">id_</span></code> （上面的例子为 &quot;<code class="docutils literal notranslate"><span class="pre">id_my_field</span></code>&quot;）。你可以通过设置 <a class="reference internal" href="widgets.html#django.forms.Widget.attrs" title="django.forms.Widget.attrs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">attrs</span></code></a> 对字段的部件进行修改。例如，声明一个字段是这样的：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">my_field</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;id&#39;</span><span class="p">:</span> <span class="s1">&#39;myFIELD&#39;</span><span class="p">}))</span>
</pre></div>
</div>
<p>并使用上面的模板，会呈现出这样的效果：</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">&quot;myFIELD&quot;</span><span class="p">&gt;</span>...<span class="p">&lt;/</span><span class="nt">label</span><span class="p">&gt;&lt;</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;myFIELD&quot;</span> <span class="na">type</span><span class="o">=</span><span class="s">&quot;text&quot;</span> <span class="na">name</span><span class="o">=</span><span class="s">&quot;my_field&quot;</span> <span class="na">required</span><span class="p">&gt;</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.initial">
<code class="descclassname">BoundField.</code><code class="descname">initial</code><a class="headerlink" href="#django.forms.BoundField.initial" title="永久链接至目标">¶</a></dt>
<dd><p>Use <a class="reference internal" href="#django.forms.BoundField.initial" title="django.forms.BoundField.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">BoundField.initial</span></code></a> to retrieve initial data for a form field.
It retrieves the data from <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.initial</span></code></a> if present, otherwise
trying <a class="reference internal" href="fields.html#django.forms.Field.initial" title="django.forms.Field.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Field.initial</span></code></a>. Callable values are evaluated. See
<a class="reference internal" href="#ref-forms-initial-form-values"><span class="std std-ref">初始表单值</span></a> for more examples.</p>
<p><a class="reference internal" href="#django.forms.BoundField.initial" title="django.forms.BoundField.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">BoundField.initial</span></code></a> caches its return value, which is useful
especially when dealing with callables whose return values can change (e.g.
<code class="docutils literal notranslate"><span class="pre">datetime.now</span></code> or <code class="docutils literal notranslate"><span class="pre">uuid.uuid4</span></code>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">DatedCommentForm</span><span class="p">(</span><span class="n">CommentForm</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">created</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">DateTimeField</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">DatedCommentForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;created&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">initial</span>
<span class="go">datetime.datetime(2021, 7, 27, 9, 5, 54)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;created&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">initial</span>
<span class="go">datetime.datetime(2021, 7, 27, 9, 5, 54)</span>
</pre></div>
</div>
<p>Using <a class="reference internal" href="#django.forms.BoundField.initial" title="django.forms.BoundField.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">BoundField.initial</span></code></a> is recommended over
<a class="reference internal" href="#django.forms.Form.get_initial_for_field" title="django.forms.Form.get_initial_for_field"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_initial_for_field()</span></code></a>.</p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.is_hidden">
<code class="descclassname">BoundField.</code><code class="descname">is_hidden</code><a class="headerlink" href="#django.forms.BoundField.is_hidden" title="永久链接至目标">¶</a></dt>
<dd><p>如果这个 <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a> 的部件被隐藏，返回 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.label">
<code class="descclassname">BoundField.</code><code class="descname">label</code><a class="headerlink" href="#django.forms.BoundField.label" title="永久链接至目标">¶</a></dt>
<dd><p>字段的 <a class="reference internal" href="fields.html#django.forms.Field.label" title="django.forms.Field.label"><code class="xref py py-attr docutils literal notranslate"><span class="pre">label</span></code></a>。这在 <a class="reference internal" href="#django.forms.BoundField.label_tag" title="django.forms.BoundField.label_tag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">label_tag()</span></code></a> 中使用。</p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.name">
<code class="descclassname">BoundField.</code><code class="descname">name</code><a class="headerlink" href="#django.forms.BoundField.name" title="永久链接至目标">¶</a></dt>
<dd><p>表单中该字段的名称：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="go">subject</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="go">message</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.BoundField.widget_type">
<code class="descclassname">BoundField.</code><code class="descname">widget_type</code><a class="headerlink" href="#django.forms.BoundField.widget_type" title="永久链接至目标">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 3.1.</span> </div>
<p>返回包装字段的部件的小写类名，去掉后面的 <code class="docutils literal notranslate"><span class="pre">input</span></code> 或 <code class="docutils literal notranslate"><span class="pre">widget</span></code>。当构建表单时，布局取决于组件的类型时，可以使用这个方法。例如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="n">form</span> <span class="o">%</span><span class="p">}</span>
    <span class="p">{</span><span class="o">%</span> <span class="k">if</span> <span class="n">field</span><span class="o">.</span><span class="n">widget_type</span> <span class="o">==</span> <span class="s1">&#39;checkbox&#39;</span> <span class="o">%</span><span class="p">}</span>
        <span class="c1"># render one way</span>
    <span class="p">{</span><span class="o">%</span> <span class="k">else</span> <span class="o">%</span><span class="p">}</span>
        <span class="c1"># render another way</span>
    <span class="p">{</span><span class="o">%</span> <span class="n">endif</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="n">endfor</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
</dd></dl>

</div>
<div class="section" id="s-methods-of-boundfield">
<span id="methods-of-boundfield"></span><h3><code class="docutils literal notranslate"><span class="pre">BoundField</span></code> 方法<a class="headerlink" href="#methods-of-boundfield" title="永久链接至标题">¶</a></h3>
<dl class="method">
<dt id="django.forms.BoundField.as_hidden">
<code class="descclassname">BoundField.</code><code class="descname">as_hidden</code>(<em>attrs=None</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.forms.BoundField.as_hidden" title="永久链接至目标">¶</a></dt>
<dd><p>返回将其表示为 <code class="docutils literal notranslate"><span class="pre">&lt;input</span> <span class="pre">type=&quot;hidden&quot;&gt;</span></code> 的 HTML 字符串。</p>
<p><code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> 传递给 <a class="reference internal" href="#django.forms.BoundField.as_widget" title="django.forms.BoundField.as_widget"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_widget()</span></code></a>。</p>
<p>这个方法主要在内部使用。你应该使用部件来代替。</p>
</dd></dl>

<dl class="method">
<dt id="django.forms.BoundField.as_widget">
<code class="descclassname">BoundField.</code><code class="descname">as_widget</code>(<em>widget=None</em>, <em>attrs=None</em>, <em>only_initial=False</em>)<a class="headerlink" href="#django.forms.BoundField.as_widget" title="永久链接至目标">¶</a></dt>
<dd><p>通过渲染通过的部件来渲染该字段，并添加作为 <code class="docutils literal notranslate"><span class="pre">attrs</span></code> 传递的任何 HTML 属性。 如果没有指定部件，那么将使用该字段的默认部件。</p>
<p><code class="docutils literal notranslate"><span class="pre">only_initial</span></code> 是 Django 内部使用的，不应该明确设置。</p>
</dd></dl>

<dl class="method">
<dt id="django.forms.BoundField.css_classes">
<code class="descclassname">BoundField.</code><code class="descname">css_classes</code>(<em>extra_classes=None</em>)<a class="headerlink" href="#django.forms.BoundField.css_classes" title="永久链接至目标">¶</a></dt>
<dd><p>当你使用 Django 的渲染快捷方式时，CSS 类被用来指示必填的表单字段或包含错误的字段。如果你是手动渲染表单，你可以使用 <code class="docutils literal notranslate"><span class="pre">css_classes</span></code> 方法访问这些 CSS 类：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">css_classes</span><span class="p">()</span>
<span class="go">&#39;required&#39;</span>
</pre></div>
</div>
<p>如果你想在可能需要的错误和必要的类之外提供一些额外的类，你可以提供这些类作为参数：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">css_classes</span><span class="p">(</span><span class="s1">&#39;foo bar&#39;</span><span class="p">)</span>
<span class="go">&#39;foo bar required&#39;</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="django.forms.BoundField.label_tag">
<code class="descclassname">BoundField.</code><code class="descname">label_tag</code>(<em>contents=None</em>, <em>attrs=None</em>, <em>label_suffix=None</em>)<a class="headerlink" href="#django.forms.BoundField.label_tag" title="永久链接至目标">¶</a></dt>
<dd><p>要单独呈现一个表单字段的标签，可以调用它的 <code class="docutils literal notranslate"><span class="pre">label_tag()</span></code> 方法：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">&#39;message&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">label_tag</span><span class="p">())</span>
<span class="go">&lt;label for=&quot;id_message&quot;&gt;Message:&lt;/label&gt;</span>
</pre></div>
</div>
<p>你可以提供 <code class="docutils literal notranslate"><span class="pre">contents</span></code> 参数，它将取代自动生成的标签标签。<code class="docutils literal notranslate"><span class="pre">attrs</span></code> 字典可以包含 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签的附加属性。</p>
<p>生成的 HTML 包括表单的 <a class="reference internal" href="#django.forms.Form.label_suffix" title="django.forms.Form.label_suffix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">label_suffix</span></code></a> （默认为冒号），如果设置了，则包括当前字段的 <a class="reference internal" href="fields.html#django.forms.Field.label_suffix" title="django.forms.Field.label_suffix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">label_suffix</span></code></a>。可选的 <code class="docutils literal notranslate"><span class="pre">label_suffix</span></code> 参数允许你覆盖任何先前设置的后缀。例如，你可以使用一个空字符串来隐藏选定字段的标签。如果你需要在模板中这样做，你可以写一个自定义过滤器来允许传递参数到 <code class="docutils literal notranslate"><span class="pre">label_tag</span></code>。</p>
</dd></dl>

<dl class="method">
<dt id="django.forms.BoundField.value">
<code class="descclassname">BoundField.</code><code class="descname">value</code>()<a class="headerlink" href="#django.forms.BoundField.value" title="永久链接至目标">¶</a></dt>
<dd><p>使用此方法渲染此字段的原始值，如同 <code class="docutils literal notranslate"><span class="pre">Widget</span></code>：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">initial</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;welcome&#39;</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">unbound_form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="n">initial</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bound_form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hi&#39;</span><span class="p">},</span> <span class="n">initial</span><span class="o">=</span><span class="n">initial</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">unbound_form</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">value</span><span class="p">())</span>
<span class="go">welcome</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">bound_form</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">value</span><span class="p">())</span>
<span class="go">hi</span>
</pre></div>
</div>
</dd></dl>

</div>
</div>
<div class="section" id="s-customizing-boundfield">
<span id="customizing-boundfield"></span><h2>自定义 <code class="docutils literal notranslate"><span class="pre">BoundField</span></code><a class="headerlink" href="#customizing-boundfield" title="永久链接至标题">¶</a></h2>
<p>如果你需要访问模板中表单字段的一些附加信息，而使用 <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> 的子类还不够，也可以考虑自定义 <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a>。</p>
<p>自定义表单字段可以覆盖 <code class="docutils literal notranslate"><span class="pre">get_bound_field()</span></code>。</p>
<dl class="method">
<dt id="django.forms.Field.get_bound_field">
<code class="descclassname">Field.</code><code class="descname">get_bound_field</code>(<em>form</em>, <em>field_name</em>)<a class="headerlink" href="#django.forms.Field.get_bound_field" title="永久链接至目标">¶</a></dt>
<dd><p>取一个 <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> 的实例和字段名。当在模板中访问该字段时，将使用返回值。它很可能是 <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a> 的一个子类的实例。</p>
</dd></dl>

<p>例如，如果你有一个 <code class="docutils literal notranslate"><span class="pre">GPSCoordinatesField</span></code>，并希望能够在模板中访问关于坐标的附加信息，可以按以下方式实现：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">GPSCoordinatesBoundField</span><span class="p">(</span><span class="n">BoundField</span><span class="p">):</span>
    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">country</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Return the country the coordinates lie in or None if it can&#39;t be</span>
<span class="sd">        determined.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">value</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">value</span><span class="p">()</span>
        <span class="k">if</span> <span class="n">value</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">get_country_from_coordinates</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">None</span>

<span class="k">class</span> <span class="nc">GPSCoordinatesField</span><span class="p">(</span><span class="n">Field</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">get_bound_field</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form</span><span class="p">,</span> <span class="n">field_name</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">GPSCoordinatesBoundField</span><span class="p">(</span><span class="n">form</span><span class="p">,</span> <span class="bp">self</span><span class="p">,</span> <span class="n">field_name</span><span class="p">)</span>
</pre></div>
</div>
<p>现在你可以在模板中使用 <code class="docutils literal notranslate"><span class="pre">{{form.coordinates.country</span> <span class="pre">}}</span></code> 访问国家。</p>
</div>
<div class="section" id="s-binding-uploaded-files-to-a-form">
<span id="s-binding-uploaded-files"></span><span id="binding-uploaded-files-to-a-form"></span><span id="binding-uploaded-files"></span><h2>将上传的文件绑定到表单中<a class="headerlink" href="#binding-uploaded-files-to-a-form" title="永久链接至标题">¶</a></h2>
<p>处理有 <code class="docutils literal notranslate"><span class="pre">FileField</span></code> 和 <code class="docutils literal notranslate"><span class="pre">ImageField</span></code> 字段的表单比普通表单要复杂一些。</p>
<p>首先，为了上传文件，你需要确保你的 <code class="docutils literal notranslate"><span class="pre">&lt;form&gt;</span></code> 元素正确地将 <code class="docutils literal notranslate"><span class="pre">enctype</span></code> 定义为 <code class="docutils literal notranslate"><span class="pre">&quot;multipart/form-data&quot;</span></code>：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">form</span> <span class="n">enctype</span><span class="o">=</span><span class="s2">&quot;multipart/form-data&quot;</span> <span class="n">method</span><span class="o">=</span><span class="s2">&quot;post&quot;</span> <span class="n">action</span><span class="o">=</span><span class="s2">&quot;/foo/&quot;</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>其次，当你使用表单时，你需要绑定文件数据。文件数据与普通的表单数据是分开处理的，所以当你的表单包含一个 <code class="docutils literal notranslate"><span class="pre">FileField</span></code> 和 <code class="docutils literal notranslate"><span class="pre">ImageField</span></code> 时，你需要在绑定表单时指定第二个参数。因此，如果我们扩展我们的 ContactForm，包含一个名为 <code class="docutils literal notranslate"><span class="pre">mugshot</span></code> 的 <code class="docutils literal notranslate"><span class="pre">ImageField</span></code>，我们需要绑定包含 mugshot 图片的文件数据：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Bound form with an image field</span>
<span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">django.core.files.uploadedfile</span> <span class="kn">import</span> <span class="n">SimpleUploadedFile</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;subject&#39;</span><span class="p">:</span> <span class="s1">&#39;hello&#39;</span><span class="p">,</span>
<span class="o">...</span>         <span class="s1">&#39;message&#39;</span><span class="p">:</span> <span class="s1">&#39;Hi there&#39;</span><span class="p">,</span>
<span class="o">...</span>         <span class="s1">&#39;sender&#39;</span><span class="p">:</span> <span class="s1">&#39;foo@example.com&#39;</span><span class="p">,</span>
<span class="o">...</span>         <span class="s1">&#39;cc_myself&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">file_data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;mugshot&#39;</span><span class="p">:</span> <span class="n">SimpleUploadedFile</span><span class="p">(</span><span class="s1">&#39;face.jpg&#39;</span><span class="p">,</span> <span class="o">&lt;</span><span class="n">file</span> <span class="n">data</span><span class="o">&gt;</span><span class="p">)}</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithMugshot</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">file_data</span><span class="p">)</span>
</pre></div>
</div>
<p>在实践中，你通常会指定 <code class="docutils literal notranslate"><span class="pre">request.FILES</span></code> 作为文件数据的来源（就像你使用 <code class="docutils literal notranslate"><span class="pre">request.POST</span></code> 作为表单数据的来源一样）：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Bound form with an image field, data from the request</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithMugshot</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="p">,</span> <span class="n">request</span><span class="o">.</span><span class="n">FILES</span><span class="p">)</span>
</pre></div>
</div>
<p>构造非绑定表单的方法和以往一样——省略表单数据 <em>和</em> 文件数据：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Unbound form with an image field</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithMugshot</span><span class="p">()</span>
</pre></div>
</div>
<div class="section" id="s-testing-for-multipart-forms">
<span id="testing-for-multipart-forms"></span><h3>多部分表格的测试<a class="headerlink" href="#testing-for-multipart-forms" title="永久链接至标题">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.is_multipart">
<code class="descclassname">Form.</code><code class="descname">is_multipart</code>()<a class="headerlink" href="#django.forms.Form.is_multipart" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>如果你正在编写可重用的视图或模板，你可能无法提前知道你的表单是否是一个多部分表单。<code class="docutils literal notranslate"><span class="pre">is_multipart()</span></code> 方法可以告诉你表单是否需要多部分编码来提交：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithMugshot</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_multipart</span><span class="p">()</span>
<span class="go">True</span>
</pre></div>
</div>
<p>下面是一个如何在模板中使用的例子：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="k">if</span> <span class="n">form</span><span class="o">.</span><span class="n">is_multipart</span> <span class="o">%</span><span class="p">}</span>
    <span class="o">&lt;</span><span class="n">form</span> <span class="n">enctype</span><span class="o">=</span><span class="s2">&quot;multipart/form-data&quot;</span> <span class="n">method</span><span class="o">=</span><span class="s2">&quot;post&quot;</span> <span class="n">action</span><span class="o">=</span><span class="s2">&quot;/foo/&quot;</span><span class="o">&gt;</span>
<span class="p">{</span><span class="o">%</span> <span class="k">else</span> <span class="o">%</span><span class="p">}</span>
    <span class="o">&lt;</span><span class="n">form</span> <span class="n">method</span><span class="o">=</span><span class="s2">&quot;post&quot;</span> <span class="n">action</span><span class="o">=</span><span class="s2">&quot;/foo/&quot;</span><span class="o">&gt;</span>
<span class="p">{</span><span class="o">%</span> <span class="n">endif</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{{</span> <span class="n">form</span> <span class="p">}}</span>
<span class="o">&lt;/</span><span class="n">form</span><span class="o">&gt;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-subclassing-forms">
<span id="subclassing-forms"></span><h2>子类化表单<a class="headerlink" href="#subclassing-forms" title="永久链接至标题">¶</a></h2>
<p>如果你有多个共享字段的 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 类，你可以使用子类来消除冗余。</p>
<p>当你将一个自定义的 <code class="docutils literal notranslate"><span class="pre">Form</span></code> 类子类化时，生成的子类将包括父类的所有字段，然后是你在子类中定义的字段。</p>
<p>在这个例子中，<code class="docutils literal notranslate"><span class="pre">ContactFormWithPriority</span></code> 包含了 <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> 的所有字段，加上一个额外的字段 <code class="docutils literal notranslate"><span class="pre">priority</span></code>。<code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> 字段是按顺序排列的：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">ContactFormWithPriority</span><span class="p">(</span><span class="n">ContactForm</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">priority</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithPriority</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;Subject: &lt;input type=&quot;text&quot; name=&quot;subject&quot; maxlength=&quot;100&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Message: &lt;input type=&quot;text&quot; name=&quot;message&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Sender: &lt;input type=&quot;email&quot; name=&quot;sender&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Cc myself: &lt;input type=&quot;checkbox&quot; name=&quot;cc_myself&quot;&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Priority: &lt;input type=&quot;text&quot; name=&quot;priority&quot; required&gt;&lt;/li&gt;</span>
</pre></div>
</div>
<p>可以对多个表单进行子类化，将表单视为混搭。在这个例子中，<code class="docutils literal notranslate"><span class="pre">BeatleForm</span></code> 同时对 <code class="docutils literal notranslate"><span class="pre">PersonForm</span></code> 和 <code class="docutils literal notranslate"><span class="pre">InstrumentForm</span></code> 进行子类化（按顺序），它的字段列表包括父类的字段：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">PersonForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">first_name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">last_name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">InstrumentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">instrument</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">BeatleForm</span><span class="p">(</span><span class="n">InstrumentForm</span><span class="p">,</span> <span class="n">PersonForm</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">haircut_type</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">BeatleForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">b</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;First name: &lt;input type=&quot;text&quot; name=&quot;first_name&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Last name: &lt;input type=&quot;text&quot; name=&quot;last_name&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Instrument: &lt;input type=&quot;text&quot; name=&quot;instrument&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Haircut type: &lt;input type=&quot;text&quot; name=&quot;haircut_type&quot; required&gt;&lt;/li&gt;</span>
</pre></div>
</div>
<p>可以通过在子类上将字段名称设置为 &quot;<code class="docutils literal notranslate"><span class="pre">None</span></code>&quot; 来声明性地删除从父类继承的 <code class="docutils literal notranslate"><span class="pre">Field</span></code>。例如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">ParentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">age</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">IntegerField</span><span class="p">()</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">ChildForm</span><span class="p">(</span><span class="n">ParentForm</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">name</span> <span class="o">=</span> <span class="kc">None</span>

<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">ChildForm</span><span class="p">()</span><span class="o">.</span><span class="n">fields</span><span class="p">)</span>
<span class="go">[&#39;age&#39;]</span>
</pre></div>
</div>
</div>
<div class="section" id="s-prefixes-for-forms">
<span id="s-form-prefix"></span><span id="prefixes-for-forms"></span><span id="form-prefix"></span><h2>表单前缀<a class="headerlink" href="#prefixes-for-forms" title="永久链接至标题">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.prefix">
<code class="descclassname">Form.</code><code class="descname">prefix</code><a class="headerlink" href="#django.forms.Form.prefix" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>你可以在一个 <code class="docutils literal notranslate"><span class="pre">&lt;form&gt;</span></code> 标签中放入多个 Django 表单。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mother</span> <span class="o">=</span> <span class="n">PersonForm</span><span class="p">(</span><span class="n">prefix</span><span class="o">=</span><span class="s2">&quot;mother&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">father</span> <span class="o">=</span> <span class="n">PersonForm</span><span class="p">(</span><span class="n">prefix</span><span class="o">=</span><span class="s2">&quot;father&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">mother</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_mother-first_name&quot;&gt;First name:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;mother-first_name&quot; id=&quot;id_mother-first_name&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_mother-last_name&quot;&gt;Last name:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;mother-last_name&quot; id=&quot;id_mother-last_name&quot; required&gt;&lt;/li&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">father</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_father-first_name&quot;&gt;First name:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;father-first_name&quot; id=&quot;id_father-first_name&quot; required&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;&lt;label for=&quot;id_father-last_name&quot;&gt;Last name:&lt;/label&gt; &lt;input type=&quot;text&quot; name=&quot;father-last_name&quot; id=&quot;id_father-last_name&quot; required&gt;&lt;/li&gt;</span>
</pre></div>
</div>
<p>也可以在表单类上指定前缀：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">PersonForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="o">...</span>
<span class="gp">... </span>    <span class="n">prefix</span> <span class="o">=</span> <span class="s1">&#39;person&#39;</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">表单 API</a><ul>
<li><a class="reference internal" href="#bound-and-unbound-forms">绑定和非绑定表单</a></li>
<li><a class="reference internal" href="#using-forms-to-validate-data">使用表单来验证数据</a><ul>
<li><a class="reference internal" href="#behavior-of-unbound-forms">非绑定表单的行为</a></li>
</ul>
</li>
<li><a class="reference internal" href="#initial-form-values">初始表单值</a></li>
<li><a class="reference internal" href="#checking-which-form-data-has-changed">检查哪些表格数据已经改变</a></li>
<li><a class="reference internal" href="#accessing-the-fields-from-the-form">访问表单中的字段</a></li>
<li><a class="reference internal" href="#accessing-clean-data">访问“干净的”数据</a></li>
<li><a class="reference internal" href="#outputting-forms-as-html">将表单输出为 HTML</a><ul>
<li><a class="reference internal" href="#as-p"><code class="docutils literal notranslate"><span class="pre">as_p()</span></code></a></li>
<li><a class="reference internal" href="#as-ul"><code class="docutils literal notranslate"><span class="pre">as_ul()</span></code></a></li>
<li><a class="reference internal" href="#as-table"><code class="docutils literal notranslate"><span class="pre">as_table()</span></code></a></li>
<li><a class="reference internal" href="#styling-required-or-erroneous-form-rows">样式化必填或错误的表单行</a></li>
<li><a class="reference internal" href="#configuring-form-elements-html-id-attributes-and-label-tags">设置表单元素的 HTML <code class="docutils literal notranslate"><span class="pre">id</span></code> 属性和 <code class="docutils literal notranslate"><span class="pre">&lt;label&gt;</span></code> 标签。</a></li>
<li><a class="reference internal" href="#configuring-the-rendering-of-a-form-s-widgets">设置表单组件的渲染方式</a></li>
<li><a class="reference internal" href="#notes-on-field-ordering">字段顺序的注意事项</a></li>
<li><a class="reference internal" href="#how-errors-are-displayed">如何显示错误</a></li>
<li><a class="reference internal" href="#customizing-the-error-list-format">自定义错误列表格式</a></li>
</ul>
</li>
<li><a class="reference internal" href="#more-granular-output">更精细的输出</a><ul>
<li><a class="reference internal" href="#attributes-of-boundfield"><code class="docutils literal notranslate"><span class="pre">BoundField</span></code> 的属性</a></li>
<li><a class="reference internal" href="#methods-of-boundfield"><code class="docutils literal notranslate"><span class="pre">BoundField</span></code> 方法</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizing-boundfield">自定义 <code class="docutils literal notranslate"><span class="pre">BoundField</span></code></a></li>
<li><a class="reference internal" href="#binding-uploaded-files-to-a-form">将上传的文件绑定到表单中</a><ul>
<li><a class="reference internal" href="#testing-for-multipart-forms">多部分表格的测试</a></li>
</ul>
</li>
<li><a class="reference internal" href="#subclassing-forms">子类化表单</a></li>
<li><a class="reference internal" href="#prefixes-for-forms">表单前缀</a></li>
</ul>
</li>
</ul>

  <h4>上一个主题</h4>
  <p class="topless"><a href="index.html"
                        title="上一章">表单</a></p>
  <h4>下一个主题</h4>
  <p class="topless"><a href="fields.html"
                        title="下一章">表单字段</a></p>
  <div role="note" aria-label="source link">
    <h3>本页</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/ref/forms/api.txt"
            rel="nofollow">显示源代码</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>快速搜索</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="转向" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">12月 07, 2021</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="index.html" title="表单">previous</a>
     |
    <a href="../index.html" title="API 参考" accesskey="U">up</a>
   |
    <a href="fields.html" title="表单字段">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>